feat(i18n): internationalization across the API and both React apps - #1344

Implements internationalization (i18n) with multi-language support across the backend API and both React front-ends, following up on the discussion in #1301 (branched off v10 GA as suggested).

On the split request. Everything below is the review being closed on this branch first, so the three PRs are cut from a tree that is already correct rather than each carrying its own version of these fixes. Several of them do not respect the split boundary — the impersonation locale fix spans both apps, and the pt-BR catalog convention spans the framework resx and both front-end catalogs — so landing them once here is strictly less work to review than landing them three times. Say the word and the framework PR goes up next.

⚠️ Touches protected src/BuildingBlocks (Golden Rule #4)

The previous description omitted this, which was wrong. Eighteen files, needing maintainer sign-off:

Core — Core.csproj; Exceptions/ (CustomException, ForbiddenException, UnauthorizedException, and the new ILocalizableMessage, LocalizedKeyNotFoundException, LocalizedUnauthorizedAccessException); Localization/ (new SharedResources marker + SupportedCultures + the two shared catalogs).

Web — Extensions.cs (registers and orders the localization middleware, +6 lines); Exceptions/GlobalExceptionHandler.cs; Validation/PagedQueryValidator.cs; new Localization/ (LocalizationExtensions, UserLocaleRequestCultureProvider).

Jobs — Extensions.cs, one exception message. Storage — QuotaMeteredStorageService.cs, one exception message.

No existing behaviour of other building blocks is altered. src/Directory.Packages.props carries one addition, the SSH.NET pin discussed at the end of this description; the pin this branch used to carry for System.Security.Cryptography.Xml is already on main, so nothing else in that file differs.

UseRequestLocalization sets the UI culture only

You asked whether UI-culture-only was considered. It is now what ships.

main has no request localization at all, so pinning the formatting culture is less change than negotiating it: CultureInfo.CurrentCulture behaves exactly as it does on main today, and only resource lookup follows the request. For an API whose output is JSON that is the safer default, and it makes the CA1305 question moot rather than merely bounded.

It is not one switch. RequestLocalizationMiddleware.SetCurrentThreadCulture assigns both cultures unconditionally, so the culture half has to be pinned:

• DefaultRequestCulture carries (InvariantCulture, configured default). The middleware resolves the culture half as cultureInfo ??= DefaultRequestCulture.Culture, making invariant the only reachable value.
• SupportedCultures is null, so the middleware skips culture filtering entirely. A one-element [InvariantCulture] list behaves identically but logs UnsupportedCultures on every request — the middleware's parent-culture walk bails at the empty culture name, so invariant is unmatchable by design.

With formatting out of the negotiation, the neutral pt/en entries bought nothing and are gone; SupportedCultures.Tags is the single, specific-only list. A request asking for a bare pt or an unsupported variant now resolves to the configured default. Both React apps canonicalise variants onto supported tags before calling the API, so app traffic is unaffected; a hand-rolled client sending bare pt gets the default.

Message arguments are culture-insensitive too. The localizer formats with string.Format under CurrentCulture, so a double or DateTime in a message would render with an invariant separator. Every MessageArgs site and every localizer["…", …] call site was enumerated: all int, long, string or enum, except MaxWindow.TotalDays in the two audit-window validators, which is now an int at the source.

Catalogs are named for specific cultures

SharedResources.pt.resx and the ten module catalogs are now *.pt-BR.resx, matching the front-end. Pure renames, no string changed.

The asymmetry you flagged is gone, and so is the trap behind it: a future pt-PT is no longer served Brazilian strings by parent fallback. The documented consequence is that a bare pt or an unsupported variant lands on the neutral English catalog rather than on Portuguese. Adding a language is now: add the specific tag to SupportedCultures.Tags, add a *.{tag}.resx per catalog, add the JSON catalogs to both apps, and drop it from the front-end CANON map if it was being folded into another tag. .agents/rules/localization.md records all of this.

The Locale column

The old summary was wrong: there is no DB default. The column is nullable with en-US as a code-level fallback, and it is now character varying(10) rather than unbounded text — 10 covers language-script-region (zh-Hant-TW). AddUserLocale was edited in place rather than stacked with an ALTER, since it has never shipped in a release.

Confirmed as you asked: Validation.UnsupportedLocale is wired at the write boundary. UpdateUserCommandValidator restricts Locale to SupportedCultures.Tags, on PUT /identity/profile, via the Mediator ValidationBehavior. The column constraint is the storage-level backstop, not the validation.

Known behaviour (documented, not bugs)

• The locale claim lags a language switch by one token. The provider reads the JWT claim, so a switch reaches the API at the next token issue. The front-end persists to the profile and re-mints, so it converges; in between, the shell can be in the new language while an API error is still in the old one. The alternative is a per-request DB read on every authenticated call.
• SignalR does not carry the app locale. The hub client builds its own requests instead of going through apiFetch, so Accept-Language on the negotiate is the browser's. Applies to every session, not just impersonation. Named explicitly in handoff-locale.spec.ts so any other channel that stops carrying the locale fails the test.
• Middleware registered before localization renders its errors in the default language. UseExceptionHandler() sits ahead of UseHeroLocalization(), which in turn has to sit after UseAuthentication() because the culture provider reads the locale claim off HttpContext.User. An exception thrown by anything in between — HTTPS redirection, CORS, static files, routing — is therefore rendered in the configured default culture rather than the caller's. Endpoint handlers, where every localized exception in this codebase is actually thrown, are unaffected. Moving the exception handler below localization would leave those middlewares with no ProblemDetails at all, which is the worse trade, so this stays as documented behaviour rather than being papered over.

Fixed since the last review

Three reviewer bots' P2s, plus what a five-lens adversarial pass turned up. Each was verified at the source before being treated as real, and each fix has a mutation gate — the fix is reverted, the pinning test must go red, and the file is restored byte-exact.

• The operator's language now survives cross-app impersonation. StartImpersonation strips the target's locale claim on purpose, and the two apps normally sit on different origins, so the handoff URL had no way to convey it and the API fell through to the dashboard's own browser detection. The handoff now carries locale; the dashboard adopts it before createRoot, which fixes the shell and Accept-Language at once. Chosen over an actor-locale token claim: it leaves the token contract and the framework culture provider untouched.
• Unmapped status codes are no longer titled "an unexpected error occurred". TitleKeyFor sent everything outside four statuses to Error.Unexpected; the type-name fallback beside it only fires on ResourceNotFound, and that key resolves, so it never fired. Every one of the 41 Conflict throw sites across Billing and Catalog answered Status: 409 with a title contradicting its own detail. This branch regressed that — before it, Title was the exception type name. Unmapped statuses now fall back to the type name again, and Conflict gets a real localized title.
• A stale persisted locale no longer reverts the chosen language. updateMyProfile is a read-modify-write with no concurrency token, and Settings › Profile invalidates the same ["identity","me"] key the topbar reads, so a save whose read preceded the language PUT could echo the old locale back and win. The topbar's hydration effect then changed the UI language to it. Hydration now stops once the user chooses a language in-session; a locale set on another device still carries over on a fresh mount. The underlying lost update is a contract change to PUT /identity/profile and is tracked separately in #1359.
• The document element declares the active locale. Both apps shipped a static lang="en" that nothing updated, so a Portuguese UI announced itself as English to screen readers and browser translation.
• Test gaps the audit found. A built-in-validation test asserted only the absence of the English string (satisfied by a blank message or a leaked resource key) and now pins the Portuguese text. ExceptionSeverityClassifier was never exercised with the Localized* subclasses, even though those subclass the BCL types precisely to keep audit severity classification working — changing a base type would have silently reclassified every unauthorized access with the suite green.
• Catalog parity is now enforced generically. Notifications shipped a catalog with no parity test and has no test project to hold one. CatalogParityTests discovers every catalog by reflection and compares each culture's own key set with tryParents: false, plus the placeholder-index set per key — {1} present in one culture and not the other throws FormatException at render time, in that culture only. New module catalogs are covered without a new test.

The SSH.NET pin is carried from #1333

NU1903 / GHSA-q939-rpr3-3284 on SSH.NET 2025.1.0, pulled transitively by Testcontainers, fails restore for the whole solution under TreatWarningsAsErrors — on main too: dotnet restore src/FSH.Starter.slnx at 3f2959e6 fails identically. It is not introduced here, and the fix properly belongs to #1333.

Rather than leave this PR red on someone else's advisory, the pin is carried here byte-identical to #1333's version of the file, comment included. That keeps both mergeable in either order: git merge-tree on both orderings yields a clean tree holding a single SSH.NET entry, and the merged file is identical to what #1333 alone produces. The byte identity is what buys that — the same pin under a reworded comment conflicts. So if #1333's pin changes during review this copy should be matched rather than allowed to drift, and once #1333 lands first it can simply be dropped from here.

Testing

• Backend: 15 test assemblies, 1891 passed / 0 failed / 1 skipped, including Integration (Testcontainers/Postgres, Docker) at 746 passed / 1 skipped.
• Front-end: build, test-suite typecheck, lint and the full Playwright suite green in both apps — admin 135 passed, dashboard 183 passed, no flaky, none skipped.
• Every fix carries a mutation gate with a byte-exact restore.

Not pinned, and stated rather than glossed: the hydration guard has no regression test. Reproducing it needs an in-mount profile refetch driven through the Settings form, and the click races the language-change re-render (element detached from the DOM). Three distinct approaches, then stopped rather than paper over it with retries or a longer timeout.

Notes

• en-US and pt-BR are held at strict key and placeholder parity, enforced by tests, so a missing or mis-arged translation fails the build instead of shipping English.
• Documentation and a changelog entry land with the framework PR (Golden Rule Localization with JSON files #10), since code on ProblemDetails and the new config section are public contract.